home *** CD-ROM | disk | FTP | other *** search
/ Stone Design / Stone Design.iso / Stone_Friends / Wave / WavesWorld / Source / Libraries / tcl7.4b3 / doc / Async.3 < prev    next >
Encoding:
Text File  |  1995-02-22  |  6.1 KB  |  160 lines
  1. '\"
  2. '\" Copyright (c) 1989-1993 The Regents of the University of California.
  3. '\" Copyright (c) 1994-1995 Sun Microsystems, Inc.
  4. '\"
  5. '\" See the file "license.terms" for information on usage and redistribution
  6. '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
  7. '\" 
  8. '\" @(#) Async.3 1.7 95/02/22 14:37:15
  9. '\" 
  10. .so man.macros
  11. .HS Tcl_AsyncCreate tclc 7.0
  12. .BS
  13. .SH NAME
  14. Tcl_AsyncCreate, Tcl_AsyncMark, Tcl_AsyncInvoke, Tcl_AsyncDelete \- handle asynchronous events
  15. .SH SYNOPSIS
  16. .nf
  17. \fB#include <tcl.h>\fR
  18. .sp
  19. extern int \fBtcl_AsyncReady\fR;
  20. .sp
  21. Tcl_AsyncHandler
  22. \fBTcl_AsyncCreate\fR(\fIproc, clientData\fR)
  23. .sp
  24. \fBTcl_AsyncMark\fR(\fIasync\fR)
  25. .sp
  26. int
  27. \fBTcl_AsyncInvoke\fR(\fIinterp, code\fR)
  28. .sp
  29. \fBTcl_AsyncDelete\fR(\fIasync\fR)
  30. .SH ARGUMENTS
  31. .AS Tcl_AsyncHandler clientData
  32. .AP Tcl_AsyncProc *proc in
  33. Procedure to invoke to handle an asynchronous event.
  34. .AP ClientData clientData in
  35. One-word value to pass to \fIproc\fR.
  36. .AP Tcl_AsyncHandler async in
  37. Token for asynchronous event handler.
  38. .AP Tcl_Interp *interp in
  39. Tcl interpreter in which command was being evaluated when handler was
  40. invoked, or NULL if handler was invoked when there was no interpreter
  41. active.
  42. .AP int code in
  43. Completion code from command that just completed in \fIinterp\fR,
  44. or 0 if \fIinterp\fR is NULL.
  45. .BE
  46.  
  47. .SH DESCRIPTION
  48. .PP
  49. These procedures provide a safe mechanism for dealing with
  50. asynchronous events such as signals.
  51. If an event such as a signal occurs while a Tcl script is being
  52. evaluated then it isn't safe to take any substantive action to
  53. process the event.
  54. For example, it isn't safe to evaluate a Tcl script since the
  55. interpreter may already be in the middle of evaluating a script;
  56. it may not even be safe to allocate memory, since a memory
  57. allocation could have been in progress when the event occurred.
  58. The only safe approach is to set a flag indicating that the event
  59. occurred, then handle the event later when the world has returned
  60. to a clean state, such as after the current Tcl command completes.
  61. .PP
  62. \fBTcl_AsyncCreate\fR creates an asynchronous handler and returns
  63. a token for it.
  64. The asynchronous handler must be created before
  65. any occurrences of the asynchronous event that it is intended
  66. to handle (it is not safe to create a handler at the time of
  67. an event).
  68. When an asynchronous event occurs the code that detects the event
  69. (such as a signal handler) should call \fBTcl_AsyncMark\fR with the
  70. token for the handler.
  71. \fBTcl_AsyncMark\fR will mark the handler as ready to execute, but it
  72. will not invoke the handler immediately.
  73. Tcl will call the \fIproc\fR associated with the handler later, when
  74. the world is in a safe state, and \fIproc\fR can then carry out
  75. the actions associated with the asynchronous event.
  76. \fIProc\fR should have arguments and result that match the
  77. type \fBTcl_AsyncProc\fR:
  78. .nf
  79. .RS
  80. typedef int Tcl_AsyncProc(
  81. .RS
  82. ClientData \fIclientData\fR,
  83. Tcl_Interp *\fIinterp\fR,
  84. int \fIcode\fR);
  85. .RE
  86. .RE
  87. .fi
  88. The \fIclientData\fR will be the same as the \fIclientData\fR
  89. argument passed to \fBTcl_AsyncCreate\fR when the handler was
  90. created.
  91. If \fIproc\fR is invoked just after a command has completed
  92. execution in an interpreter, then \fIinterp\fR will identify
  93. the interpreter in which the command was evaluated and
  94. \fIcode\fR will be the completion code returned by that
  95. command.
  96. The command's result will be present in \fIinterp->result\fR.
  97. When \fIproc\fR returns, whatever it leaves in \fIinterp->result\fR
  98. will be returned as the result of the command and the integer
  99. value returned by \fIproc\fR will be used as the new completion
  100. code for the command.
  101. .PP
  102. It is also possible for \fIproc\fR to be invoked when no interpreter
  103. is active.
  104. This can happen, for example, if an asynchronous event occurs while
  105. the application is waiting for interactive input or an X event.
  106. In this case \fIinterp\fR will be NULL and \fIcode\fR will be
  107. 0, and the return value from \fIproc\fR will be ignored.
  108. .PP
  109. The procedure \fBTcl_AsyncInvoke\fR is called to invoke all of the
  110. handlers that are ready.
  111. The global variable \fBtcl_AsyncReady\fR will be non-zero whenever any
  112. asynchronous handlers are ready;  it can be checked to avoid calls
  113. to \fBTcl_AsyncInvoke\fR when there are no ready handlers.
  114. Tcl checks \fBtcl_AsyncReady\fR after each command is evaluated
  115. and calls \fBTcl_AsyncInvoke\fR if needed.
  116. Applications may also call \fBTcl_AsyncInvoke\fR at interesting
  117. times for that application.
  118. For example, Tk's event handler checks \fBtcl_AsyncReady\fR
  119. after each event and calls \fBTcl_AsyncInvoke\fR if needed.
  120. The \fIinterp\fR and \fIcode\fR arguments to \fBTcl_AsyncInvoke\fR
  121. have the same meaning as for \fIproc\fR:  they identify the active
  122. interpreter, if any, and the completion code from the command
  123. that just completed.
  124. .PP
  125. \fBTcl_AsyncDelete\fR removes an asynchronous handler so that
  126. its \fIproc\fR will never be invoked again.
  127. A handler can be deleted even when ready, and it will still
  128. not be invoked.
  129. .PP
  130. If multiple handlers become active at the same time, the
  131. handlers are invoked in the order they were created (oldest
  132. handler first).
  133. The \fIcode\fR and \fIinterp->result\fR for later handlers
  134. reflect the values returned by earlier handlers, so that
  135. the most recently created handler has last say about
  136. the interpreter's result and completion code.
  137. If new handlers become ready while handlers are executing,
  138. \fBTcl_AsyncInvoke\fR will invoke them all;  at each point it
  139. invokes the highest-priority (oldest) ready handler, repeating
  140. this over and over until there are no longer any ready handlers.
  141.  
  142. .SH WARNING
  143. .PP
  144. It is almost always a bad idea for an asynchronous event
  145. handler to modify \fIinterp->result\fR or return a code different
  146. from its \fIcode\fR argument.
  147. This sort of behavior can disrupt the execution of scripts in
  148. subtle ways and result in bugs that are extremely difficult
  149. to track down.
  150. If an asynchronous event handler needs to evaluate Tcl scripts
  151. then it should first save \fIinterp->result\fR plus the values
  152. of the variables \fBerrorInfo\fR and \fBerrorCode\fR (this can
  153. be done, for example, by storing them in dynamic strings).
  154. When the asynchronous handler is finished it should restore
  155. \fIinterp->result\fR, \fBerrorInfo\fR, and \fBerrorCode\fR,
  156. and return the \fIcode\fR argument.
  157.  
  158. .SH KEYWORDS
  159. asynchronous event, handler, signal
  160.